rbm_remote(7)
=============

NAME
----
rbm_remote - rbm remote build

DESCRIPTION
-----------

It can be useful to run the build of your package on an external server,
a VM or a chroot. For instance if you are running an rpm based
distribution and want to build a Debian package.

To do do this, you can define the +remote_exec+ option.

The following options are used to configure the remote execution of the
build:

remote_exec::
        the template of a command used to execute a command on a remote
        host. The command to be executed is available in the option
        +exec_cmd+. The option +exec_as_root+ indicate whether the script
        should be run as a normal user, or as root. Some commands such
        as the pre and post scripts need to be run as root. The name of
        the command we are running is available in the option +exec_name+.

remote_mktemp::
        the template of a command to create a temporary directory. If
        undefined, `mktemp -d -p /var/tmp` will be used.

remote_put::
        the template of a command used to put a file on a remote host.
        The source file is available in the +put_src+ option and the
        destination directory in the +put_dst+ option. The default is
        to use tar with the +remote_exec+ option.

remote_get::
        the template of a command used to fetch a file from a remote host.
        The source directory is available in the +get_src+ option, and the
        destination directory in the +get_dst+ option. The default is
        to use tar with the +remote_exec+ option.

remote_start::
        the template of a command that will start the remote host before
        we can access it. This can be useful for instance if you need
        to start a VM, or fetch a container. If access to an input file is
        needed, the +remote_srcdir+ option is pointing to a temporary
        directory containing the input files.

remote_finish::
        the template of a command that will stop the remote host after
        we finished the build. This can be useful for instance if you
        want to shutdown a VM or remove a temporary container.

The +remote_*+ options can access the +build_id+ option which is a
unique identifier of the current build.


REMOTE BUILD WITH DOCKER
------------------------

Some predefined +remote_*+ template to run the builds in docker are
available. To enable building in docker, you can set the +remote_docker+
option to 1. The following options will then be used:

docker_image::
        The name of the docker image you want to use.

docker_save_image::
        By default the docker image used during the build will be removed
        when it is finished. If you want to keep it, you can define an
        image name in this option.

docker_opts::
        If you want to add some docker command line options, you can
        define them in this option. This could be useful for instance
        if you don't want to use the default docker instance.

docker_user::
        The user that should be used to run the build inside the
        container. If that user does not exist, it will be created
        automatically. The default is +rbm+.

For example, if you want to build your software on Fedora 20 using
docker, you can do this:

----
remote_docker: 1
docker_image: fedora:20
----


REMOTE BUILD WITH SSH
---------------------

Some predefined +remote_*+ templates are available and can be enabled
by setting the +remote_ssh+ option to 1. For instance if you want to
build your debian packages on a remote node with ssh, add the following
lines to your configuration :

----
ssh_host: some_hostname
steps:
  deb_src:
     remote_ssh: 1
----

The following options will be used:

ssh_host::
        The hostname where to connect. It can also contain a username.

ssh_port::
        Optionally you can set a port using this option. You could also
        do it by editing your +.ssh/config+ file.

ssh_options::
        Optionally you can set some ssh options, for the exec command.


BUILD IN A CHROOT
-----------------

You can use the +remote_chroot+ option if you want to build in a chroot.
This option requires that you have sudo access to the chroot command.

The following options will be used:

chroot_path::
        The path to the chroot directory.

chroot_user::
        The user in the chroot which should run the build.

Example:

----
chroot_path: /chroots/debian-wheezy
chroot_user: build
steps:
  deb:
    remote_chroot: 1
----


SEE ALSO
--------
link:rbm.html[rbm(1)],
link:rbm_config.html[rbm_config(7)]
